perm filename UPDATE.KKP[UP,DOC] blob
sn#002756 filedate 1972-06-11 generic text, type T, neo UTF8
MANUAL LIST AND UPDATE PROGRAM 1
This program is designed to allow users to list sections of
manuals which have been updated and to give writers of manuals an
easy way to specify to the users which pages have been changed. The
program has two sections. The first is a listing routine which
allows the user to specify a set of files and lists all pages that
have been changed since a specified date or update number by refering
to special update files. The other section creates and modifies the
update files to reflect new changes in the manuals.
Persons wanting to list manuals only need to read through
section B5. More flexibility in listing can be gained by reading
section B6. Persons who are responsible for updating manuals should
read this entire manual (or at least starting with B6).
MANUAL LIST AND UPDATE PROGRAM 1-1
A. MANUAL AND UPDATE FILES
The program assumes all manual listings and update files are
on the disk under [S,DOC]. The list routine will always read from
this area. The update section can be made to read from any disk area
but it will only write on the area belonging to the job running it.
Manual listings are stored on files whose names refer to the
names of the manuals and whose extensions, if any, refer to the class
of manuals that it belongs to. See L. Earnest's documentation
manual for details. This program will accept any extension except
NEW.
For each file containing a manual, there exists another file
with the same name and the extension NEW which contains the update
information for the manual. The update file consists of a series of
entries, each containing an update number, the larger the number the
more recent the update, the date the update was made (or at least the
date the update section of this program was informed of it), and a
list of the pages which were changed. If a manual file has no NEW
file, the list routine will ignore it and the update routine will
create one. The NEW file resides on [NEW,DOC].
Since the NEW file is related to the manual by the file name,
it is assumed that S,DOC has only one file of each name.
B. THE LIST ROUTINE
B1. INITIALIZATION
When started, the program types the current date. Be sure
this date is correct before continuing; the program depends on it.
Also, the UFD for S,DOC is read in. Two error messages may result:
UFD LOOKUP ERROR means the program could not access the UFD.
It is a fatal error.
FILE COUNT EXCEEDED n means the UFD contained more file names
than the program could handle, currently 256. If you
continue, only the first n files will be available. If this
happens, the program probably needs larger tables or some
files on S,DOC should be deleted.
The program then types * and is waiting for a command string.
MANUAL LIST AND UPDATE PROGRAM 1-2
B2. ABSTRACTS
The program assumes the first page of each file is the
abstract or title page and it will be listed for every file which has
other pages to be listed, even if it has not been changed. You can
force listing of only this page as explained in section B5. When the
first page is listed, the program appends to the second line a string
of the form
UPDATE 10 12-DEC-1969
with the update number and date of the most recent update listed.
This will help you remember the last update you have for when you
want to check for more recent updates.
B3. THE COMMAND STRING FOR BEGINNERS
The command string specifies a set of manuals in which the
user is interested. In addition, the user must specify a date for
each manual. All pages changed on or after the specified date will
be listed. Alternately, the user may specify an update number. All
updates with this or a larger number will be listed. If you have an
updated listing, the update number given on te first page, plus one,
will get you all more recent updates.
The file names may be given in the following forms
FOO or *.ON or *
Since only one file exists with a given names, FOO≡FOO.* and *≡*.*.
The first form specifies a single file, while the other two may
specify a set of files. DO NOT give project - programmer pairs.
A date is given in the forms
/12-DEC-1969 /-5 or /*
with no blanks in the string. /* means any date. /-5 means the
current date minus five days. In the other form, the day must always
be given and it refers to the day of the month. The month is given
as the first three letters of the month. If it is omitted, in which
case the year and the two dashes must be omitted too, the month is
assumed to be the month in which the day specified last occured. If
today is 12-DEC-1969 and you type /10, the date will be entered as
10-DEC-1969, /14 becomes 14-NOV-1969 and /12 is the current date. If
the year and last dash is missing, the last year in which the given
MANUAL LIST AND UPDATE PROGRAM 1-3
month and day occured is used. Using the above example, /10-DEC is
as before, but /14-DEC becomes 14-DEC-1968. Remember, the date typed
out at the beginning is the one used for all these default cases. If
the clock is wrong, you can lose big.
A command string consists of dates and files, seperated by
semicolons. For example:
/-1;FOO;BAZ;*.JAM
FOOBAZ;/12-DEC;SAIL
/*;*
Until a date is given, the current date is used. Once a date
is given it sticks until another date is seen. If you do not like to
type, the pair ";/" can be replaced by "/" with the same effect.
With each file, or set of files, specified, the user can
specify a date or update number for that file only, or that he only
wants the abstract. This is done by following the file name with the
specification (one only), seperated from the name by a comma. For
example, FOO,/10-JAN. The date is entered exactly as explained
earlier and supercedes the last date seen, for this file or set of
files only. The old sticky date take over again after this file. An
update number, which is a positive integer preceded by #, supercedes
the date also and applies only to this file. The string ABS after
the comma means list only the first page which, hopefully, will
contain an abstract and ignore the date If an update number is given,
a single file must have been specified, no * allowed. For abstracts
and dates a set of files may be involved. If you specify the same
file more than once the oldest update will be used. I.e.,
/-5;*.ON;FOO,/-1
will list all updates to FOO.ON on or since five days ago.
To give you a horrible example of a command string, if the
current date is 12-DEC-1969 and you type
FOO.BAZ;/10;*.SAI;MONITR,#15;STOPGAP,/-14←
EOI,ABS;MACRO
you will receive a listing of the following pages:
1. Any changes to FOO.BAZ made today.
2. Any changes to any files with the extension SAI on or since
10-DEC-1969. This date is sticky.
3. Update 15 of MONITR and all newer updates.
4. All STOPGAP changes on or since 29-NOV-1969. This date is
not sticky.
MANUAL LIST AND UPDATE PROGRAM 1-4
5. The abstract for EOI.
6. All changes to MACRO on or since 10-DEC-1969. Here is the
sticky date again.
If you type /-1;* you will get all updates made today or
yesterday for all manuals.
B4. UPDATE FILE SELECTION
After scanning the command string, the list routine finds all
files specified and checks their update file for updates on or more
recent than the date or update number specified and makes a list of
all such files as well as the date and update number of the oldest
update that will be listed. This date and number will either be the
one you specified or a more recent one. Not all update numbers will
exist if a more recent update changed all of the pages changed by the
earlier update. If the date or number is older than the oldest one
on the NEW file, you will get either the entire manual listed or a
message on the page before the abstract listing refering you to a
published copy of the manual containing all earlier revisions.
After all the files are processed, the program types out a
table giving the names of all files selected, the date and update
number stored for each as explained above, and the number of pages to
be listed for each. On a display the output will stop after 24 lines
and any character may be typed to continue the output. The total
number of pages to be listed will then be given.
If no pages are to be listed , the program exits; otherwise,
it asks if you want all this. If you do, it lists it; otherwise, it
returns for another command string so you can omit those updates you
do not want.
The following error messages may appear:
FORMAT ERROR
Error in command string. It is followed by a line feed
and the part of the string not processed. The first
character of it, or the preceding character, is where
the error was noticed. It and the next two errors
return for a new command. The old one is ignored.
NO FILE SPECIFIED
A file name was expected and was not found. Its output
and action are like the first error except that the
MANUAL LIST AND UPDATE PROGRAM 1-5
first part of the unprocessed string is the part in
error.
MONTH DOES NOT EXIST
You gave a date containing a month the routine does not
recognize. The month given is appended to the message.
xxxx.xxx NOT FOUND
You are being warned that a file, namely xxxx.xxx, which
you specified explicitly (not by use of *) was not
found. If * was used and no files were found, you are
not informed. The program continues.
xxx HAS NO UPDATE FILE
An error occured when looking up xxx.NEW. This manual
cannot be checked for updates and will be ignored.
B5. UPDATE LISTING
All updates selected are listed in the order given in the
table typed out and then the program exits. The listing is done on
device LPT on file UPDATE.LST (the enter operation is not checked for
errors). If you are on a display, the file being listed and the
total number of pages left to be listed are displayed. The rest of
the display is described under advanced features. At the end of each
manual, the program will append one page with the message
**END OF FILE**
if it reached the end of the file. If your copy is longer, the file
has been shortened.
In the listing you may find pages with a single line of the
form
DELETED - <page 1> TO <page2>
or
DELETED - <page 1> ON
This means that if any of the pages from <page 1> to, but not
including <page 2>, or from <page 1> to the end of file, exist in
your old copy, they should be deleted. Usually these pages do not
appear in the new version of the file but pages to replace them may
sometimes appear in the update listing.
MANUAL LIST AND UPDATE PROGRAM 1-6
The program processes the list of pages for all updates for a
given manual at once, listing the pages in the order they appear in
the manual. The strings are eaten as the pages are listed. If any
strings are left when the end of the manual is reached, an error is
indicated.
While you are listing, the following characters may be typed,
followed by a carriage return; all others are eaten and ignored:
P Release LPT at the end of the page being listed and wait
for more TTY input, decoded as follows: R returns to input
another command string while any other character causes the
listing to continue from where it stopped. If you are
listing onto a device other than the line printer and you
try to continue from a P or PD command, you will lose your
output file and the program will die.
PD Same as P but waits until the end of the current manual.
R Release LPT at the end of the current page and return for
another command string, ignoring the rest of the current
set of updates to be listed.
RD Same as R but wait until the end of the current manual.
S Skip to the next manual at the end of this page.
The following errors may occur while listing:
NO NEW FILE - xxxx xxxx.NEW lookup failed.
xxxx LOOKUP ERROR xxxx lookup failed. Both this and the
last error indicates something
seriously wrong since by this time the
list routine has already sucessfully
accessed both of these files. The
manual will be skipped.
FORMAT ERROR A list specification (see advanced
features), from either you or the
update file, is incorrect. The spec is
appended to the message starting at the
character where the error was noticed.
The spec is ignored to the next comma
and then listing continues. If you
MANUAL LIST AND UPDATE PROGRAM 1-7
were not using advanced features, there
is an error in the NEW file. Complain
to the author of the manual.
STRING LEFT-xxxx-n-string The list of pages for update n of file
xxxx was not completely processed
either because the pages were not given
in strictly increasing order, because a
page was specified incorrectly,or a
listed page has been deleted. The end
of file message will always appear when
this message is received. [Only
advanced users will understand the rest
of this.] The portion of the list
specification left is appended. The
first part of string will be of the
form "page specification** page
specification" and is the last part of
the string decoded (the verb has been
lost). The first non null page
specification is probably in error. If
n=-1, the list specification was
entered by you in the
B6. ADVANCE FEATURES
B6a. LIST SPECIFICATIONS
The complete command string is given in the Appendix in BNF.
A page is specified to all parts of this progrqm by means of a string
of characters which appear on the page, usually a page number. The
string can include any characters except double quote and left arrow.
The string is surrounded by double quotes. A string of N characters
will be compared against the rightmost N characters of a line on the
page, not including the carriage return and line feed. The page
specification may include one of three letters preceding the string.
F means compare the string with the end of the first line of the
page; L, the last line; and A, any (read every) line. Note that the
A option is very slow.
There are three verbs used to specify a series of consecutive
pages. They are ON, TO, and THRU. All three may be preceded by a
page specification indicating the first page of the series. If the
page specification is missing, the beginning of the file is assumed.
ON means the series terminated with the end of the file. Therefore,
MANUAL LIST AND UPDATE PROGRAM 1-8
ON by itself specifies the entire file. TO and THRU require a page
specifiection following them. TO indicates the series goes to the
second page, not including it, and THRU indicates the series goes
through the second page. A list specification, indicating pages to
be listed, consists of page specifications seperated by commas, in
increasing order. The letters F, L, and A are sticky; once one is
seen, it holds until another is seen on that line. F is assumed at
the start of the line. Note that the list specification terminates
with the first line feed seen and the effect of the letters does not
carry over from one line to the next. Also, the verb PRT, followed
by a string in double quotes, will cause a message to be printed on a
seperate page in the listing of the form
DELETED - <string>
Examples of list specifications are:
"1-1" TO "1-4","2-7", PRT"7-9 TO 8-1", "10-3" ON
L"-1-" THRU "-20-"
A"SECTION 1"TO"SECTION 4",F"COMMANDS"
When a list specification is typed to this program, blanks may
be inserted outside the double quotes for readibility. All extra
blanks are suppressed by the input routine as in the last example
above and must not appear if a NEW file is altered by STOPGAP.
This is the form of list specifications as they are typed in
and as they appear in NEW files.
B6b. PAGE DISPLAY
In addition to the display mentioned in B5, the progrqm will
display the string in the page being compared against the current
page specification. Nothing will be displayed, however, if the A
option is being used.
B6c. THE COMMAND STRING FOR EXPERTS
In section B3 it was mentioned that a date, update number, or
ABS may follow a file specification, seperated from it by a comma.
In addition, a list specification preceded by a & may follow the
comma. For example
/-3;FOO,&"3-4"TO"4-1"
MANUAL LIST AND UPDATE PROGRAM 1-9
Only a single file can be specified; no asterisks please. The
pages you have indicated will be listed even if they were not
changed. In this case, the page count given by the program will not
be correct. If you make a mistake in the list specification several
of the error messages given in B5 may result. In addition, the
following error message may occur:
SECOND SPEC STRING SEEN
A given file is specified several times in the command string and has
list specifications given for it in more than one instance. Only the
first one seen will be used.
MANUAL LIST AND UPDATE PROGRAM 2-1
C. THE UPDATE ROUTINE
C1. INITIALIZATION
The update routine is entered when you type percent for the
command string the program requests when started. You must be logged
in under S,DOC for this section to work properly. A file is
requested and you must enter the name of the file, with no
project-programmer number, containing the updated manual. It will be
looked up on S,DOC. It then asks "LIST?". If you respond with "Y",
the changed pages will be listed later in the program. Any other
response supresses listing.
The NEW file for the manual will be read in. If it does not
exist, a NEW file will be created with one entry which will cause a
listing of the entire manual. If the file has 100 entries, an error
message is printed. You will have to delete or combine some of them
using STOPGAP.
C2. SPECIFYING CHANGED PAGES
There are two methods of specifying which pages have been
updated, manual and auto. In manual mode you must tell the program
all the changed pages. In auto mode the updated manual must be on a
different file than the old copy. The program scans both files and
finds all the changed pages. The program will ask
AUTO MODE?
A "N" goes to manual mode, otherwise you get auto mode.
C2a. MANUAL MODE
In manual mode the program types
INPUT SPECS
Then you type in a list specification, as described in section B6,
specifying the changed pages in increasing order. Note that you
cannot use ← . Left arrow wll terminate the line, causing everything
MANUAL LIST AND UPDATE PROGRAM 2-2
through the next line feed to be ignored, and cacatenate the next
line typed to it onto the first line. Note that the ← does not
replace any seperators. I.e.,
/10;FOO;BAZ←
FOOBAZ
is illegal; a semicolon must appear between BAZ and FOOBAZ. There
are two special list specifications recognized by this part of the
program only. If you respond with
ALL
, the NEW file will be cleared and one entry inserted, specifying the
entire manual. The update number will be more recent than any
previously on the file. Note that "ALL" is not stored, "ON" is. The
"ALL" is given to force clearing of the rest of the NEW file. If you
respond with
PRINT "string"
(no " in the string) the NEW file is cleared as with "ALL" except the
first entry, instead of causing the entire file to be listed, will
cause the string to be listed prior to the updated pages when a user
requests an earlier update that exists on the file. The string
should tell the user how he gets a complete copy of the manual.
Presumably, he will be refered to a SAILON. If you type "PRINT"
without a string, the program will yell at you and ask you to input
the specs again.
You may also input a null list specification by giving a
carriage return for the line. See section C2c for what will be done
to you.
C2b. AUTOMATIC MODE
Auto mode may be used if both the old and new files meet the
following conditions:
1. Page numbers exist at the end of either the first or last line
of every page an are on the same line (first or last) for
every page.
2. Page numbers are of one of two forms, <page number> or
<section name>-<page number>, which may be mixed in the file.
<page number>s must be numeric.
3. <page number>s may start with any number as long as any given
section starts with the same number on both files. The
MANUAL LIST AND UPDATE PROGRAM 2-3
numbers in a section must be increasing with no gaps in the
sequence.
4. <section name>s may be either numeric or alphanumeric. The
numeric sections must be in increasing order but may have gaps
in the sequence or have alphanumeric section names mixed in.
The program may run much slower if alphanumeric section names
appear.
In auto mode, the program will ask for the name of the new
file. Include the project-programmer pair if it is not the one you
are logged in under. The program then asks
PAGE NUMBERS ON FIRST OR LAST LINE?
Give it either F or L. You will see the old and new file's page
numbers displayed. After a delay of several seconds (minutes, or
hours), the program types LIST SPEC IS: followed by the list
specification it has put together, followed by OK?. If you type N it
transfers to manual mode; anything else and the program exits to the
next section. There is no use trying auto mode over if it fails as
it will fail again, unless you alter the new file. If you feel it
should not have failed, bring listing of both files with your
complaint to K. Pingle. You will also note that the page numbers
the program is currently on will be displayed for both files while
the scan is in progress so you can tell where it is. Do not be
suprised, if you have letters in your section names, if the program
backs up occasionally. NOTE: THE SECTION DEALING WITH ALPHANUMERIC
SECTION NAMES HAS NOT BEEN DEBUGGED AS THERE ARE NO MANUALS CURRENTLY
USING THEM. IF YOU HAVE SUCH A MANUAL, CHECK WITH K. PINGLE BEFORE
USING THIS PROGRAM ON IT.
The following error messages may occur:
AUTO LOOKUP ERROR If it appears immediately, the new file
cannot be found. If it occurs later in the
scan, one of the files has become
inaccessable.
NO PAGE NUMBER A violation of either Condition 1 or 2 above
has been found.
PAGE SEQUENCE ERROR A violation of Condition 3 has been found.
A violation of Condition 5 may cause the remainder of the file
to be considered changed.
C2c. NULL MODE
MANUAL LIST AND UPDATE PROGRAM 2-4
If you type a carriage return for the list specification, no new
entries will be put in the update file but the scanning of the file
described below will still occur. This allows you to verify the
accuracy of the update information if you have altered the NEW file
by means of a text editor.
The NEW file is STOPGAP compatable and has one update entry
per line. A typical line would be
3 12-Oct-1969 19 TO"2-1","2-2"TO"3-1","4-1"ON
where the 2 is the update number and 19 the number of pages specified
in this update that are not specified for any later update. The four
fields are separated by tabs. If you insert a new entry with the
editor, remember:
1. The update numbers must be strictly increasing.
2. The dates must be in calendar order. The date of the new
entry should be the current date.
3. There are no blanks in the list specification except
possibly inside quotes.
4. Never change old entries or insert new entries except at the
end of the file.
5. Any non-zero number of pages can be given. The program will
calculate the proper number and insert it.
C3. VERIFICATION
After storing the list specification, the manual (the new
manual if auto mode was used) is scanned exactly as it would be if a
user was requesting an update listing. If you specified that you
wanted a listing, it will be made at this time. All of the error
messages given in section B6 may occur. The first two are not as
serious here, since the files have not been accessed before. The
last two indicate an error in the list specification you gave it. If
an error occurs in an earlier entry, you may have deleted a page that
was specified by the earlier entry. Use STOPGAP to fix this problem.
After the scan is finished, the page counts are updated. If any
entry has been completely superceded by later entries, it will be
MANUAL LIST AND UPDATE PROGRAM 2-5
deleted.
C4. UPDATE MANUAL
The program then types a message giving the update number,
date, and the number of pages (it should be the actual number of
pages changed for this entry) for each update. Note that if a list
specification is over 80 characters long, it will be broken at the
nearest comma prior to the 80th character and converted into several
update lines, all with the same date and update number. If there are
no commas in the first eighty characters, it types SPEC TOO LONG.
Someone has goofed. It then asks if the information is all right.
If you type anything but Y, the update routine is re-entered. If you
type Y, the NEW file is written out, then the system called. The
message
ENTER ERROR
means that the NEW file could not be entered and is fatal.
Note that the new file is not copied onto the old file if you
used auto mode. After you are satisfied that the NEW file is
correct, use the COPY command.
MANUAL LIST AND UPDATE PROGRAM 3-1
APPENDIX BNF DESCRIPTION OF THE <COMMAND_STRING>
<COMMAND_STRING> ::= <COMMAND_LIST>{carriage return}
<COMMAND_LIST> ::= <FILE_SPEC>
::= <DATE_SPEC>
::= <COMMAND_LIST><DATE_SPEC>
::= <COMMAND_LIST>;<FILE_SPEC>
::= %
::= <COMMAND_STRING>←
<DATE_SPEC> ::= /<DATE>
<DATE> ::= *
::= <DAY>
::= <DAY>-<MONTH>
::= <DAY>-<MONTH>-<YEAR>
::= -<DAY>
<DAY> ::= {1 or 2 digit number >0 specifying a day}
<MONTH> ::= JAN|FEB|MAR|APR|MAY|JUN
::= JUL|AUG|SEP|OCT|NOV|DEC
<YEAR> ::= {a 4 digit number specifying a year}
<FILE_SPEC> ::= <FILE_NAME>
::= <FILE_NAME>,<FILE_QUALIFIER_A>
::= <NAME>,<FILE_QUALIFIER_B>
::= <NAME>.<EXT>,<FILE_QUALIFIER_B>
<FILE_NAME> ::= <MANUAL>
::= <MANUAL>.<EXT>
<MANUAL> ::= *
::= <NAME>
<NAME> ::= {name of manual}
<EXT> ::= {manaul extension}
::= *
<FILE_QUALIFIER_A> ::= <DATE_SPEC>
::= ABS
<FILE_QUALIFIER_B> ::= #<UPDATE_NUMBER>
::= &<LIST_SPEC>
<UPDATE_NUMBER> ::= {positive number specifying update}
MANUAL LIST AND UPDATE PROGRAM 3-2
BNF DESCRIPTION OF LIST SPEC
<LIST_SPEC> ::= <LSPEC>
::= <LSPEC><LIST_SPEC>
::= <LIST_SPEC>← [manual mode update only]
::= ALL [manual mode update only]
::= PRINT<STRING> [manual mode update only]
<LSPEC> ::= <STRING_SPEC>
::= <STRING_SPEC>ON
::= <STRING_SPEC>TO<STRING_SPEC>
::= <STRING_SPEC>THRU<STRING_SPEC>
::= ON
::= TO<STRING_SPEC>
::= THRU<STRING_SPEC>
::= PRT<STRING>
<STRING_SPEC> ::= <STRING>
::= <LOC_SPEC><STRING>
<STRING> ::= "{string of characters not containing double
quote}"
<LOC_SPEC> ::= F
::= L
::= A